home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / LIBRARY / PBLIB1 / DOC / CODING.TXT next >
Text File  |  1993-12-24  |  11KB  |  235 lines
  1. \space 20
  2. \CENTER on
  3. TURBO PASCAL CODING CONVENTIONS
  4.  
  5. (mine 12/24/93)
  6. \space 20
  7.  
  8. \CENTER off
  9.  
  10.                                            Howard Richoux
  11.                                            6721 Shamrock Rd.
  12.                                            Lincoln, NE  68506-2821
  13.                                            (402) 488-5867
  14. \new
  15. \footer1 '@date|Turbo Pascal Coding|Page @page'
  16. General
  17. \join 72
  18.  
  19.      I have been programming for close to 25 years, on a variety
  20. of machines in a variety of languages.  Programmer support tools seem
  21. to lag far behind the language, appearing only when the machine or language
  22. is about obsolete.  I am particularly peeved with text editors.  The
  23. needs have changed little over the years, but command names and syntaxes
  24. require constant retraining of fingers.
  25.  
  26.      I am not fanatic about coding standards, although, I find it
  27. very difficult to study code which doesn't conform to my own conventions.
  28. I am willing to be persuaded to adopt any or all standards IF:
  29. \join off
  30.  
  31.      1. It doesn't require a lot of extra typing.
  32.      2. A utility is provided to convert non-conforming code to
  33.           the standard. (Not just a pretty listing).
  34.  
  35. \join on
  36.      Pascal coding conventions can be divided into (at least) two groups.
  37. General program construction practices and formatting rules.  The program
  38. construction practices include file naming, directory organization,
  39. code library/unit use and use of global variables.  Formatting rules would
  40. cover comments, indentation, capitalization and the layout of
  41. procedures within a file.
  42.  
  43.      Many conventions are historical in nature, based on earlier
  44. limitations of hardware or compilers.  Sometimes it is easier to maintain
  45. the standard than to recognize that it is no longer needed.  A few things
  46. to consider are:
  47. \join off
  48.  
  49. 1. TURBO Pascal has been around since the days of the 8088 and the 10 Mbyte
  50.      disk.  Between the improvements in the compiler and the hardware,
  51.      compile speed has increased by at least a factor of 100.
  52.  
  53. 2. The invention of the Unit is one of the great contributions to programming.
  54.      They can be compiled separately and linked intelligently, allowing code
  55.      to be placed in logical groupings with almost no penalties in compile
  56.      time or program size.
  57.  
  58. 3. Borland's implementation of Objects is another major step forward, but
  59.      I have not adapted fully to the paradigm shift.  I use them frequently,
  60.      but probably not completely correctly.  I view them more as extensions
  61.      to the Unit concept rather than as a religious experience.
  62.  
  63. 4. Code was meant to be shared.  There are enough programming jobs left to be
  64.      done that we shouldn't need to hoard our resources.  All of the general
  65.      work I am doing is placed in the PUBLIC DOMAIN.  Feel free to borrow,
  66.      modify, plagerize and utilize it.  All I would request is a footnote
  67.      in your documentation and/or the placing of some of your code into
  68.      the public domain.
  69.  
  70. \new
  71. Program Construction - General
  72. \join on
  73.  
  74.      Some of the programming conventions are forced on us by the
  75. limitations of the language/compiler.  Variables and Procedures need to be
  76. declared before they are referenced.  Some are imposed by the operating system.
  77. Fiel names can only be 8 chars with a 3 char extension, 'pas' means
  78. pascal source file, etc.
  79.  
  80.      In no particular order, here are some thoughts (Remember, I don't
  81. claim I follow all of them to the letter):
  82. \join off
  83.  
  84. 1. Minimize the use of global variables.  It is too easy to reference them
  85.      or modify them in another part of the code.  The penalty of stack use
  86.      and hence execution time is normally minimal, and is dwarfed by
  87.      improvements in hardware.  If globals are needed, hide them in Units
  88.      or objects where the scope is at least limited.
  89.  
  90. 2. *CONTROVERSIAL*  Minimize the use of COMMENTS in code.  Contrary to
  91.      conventional wisdom, I have found that commenting the obvious is
  92.      of no help later on, and the sheer mass of characters obscures the
  93.      code structure.  I have found that a large block of comments near
  94.      the beginning of a unit can document the use of variables without
  95.      obstructing code later on.
  96.  
  97. 3. Instead, Name your variables wisely.  Properly chosen names can make
  98.      the code read well and self-document.  I tend to favor mixed capitals
  99.      for variable names with the capitals at the start of words within
  100.      the names such as "PrintFlag" and "DecodeString".
  101.  
  102. 4. Indentation can drive a stranger crazy.  I can't even read code that
  103.      looks like:
  104.            IF x = 3 then
  105.              begin
  106.                DO WHILE i < 22
  107.                  begin
  108.                    z := 4;
  109.                  end;
  110.              end
  111.            else
  112.              begin
  113.                b := 1;
  114.              end;
  115.  
  116.       Some people swear by it.  ( I'm not sure I have the bad example right,
  117.       but the main feature is a snakey, constantly changing indentation.)
  118.       I use:
  119.            IF x = 3 then
  120.                 begin
  121.                 DO WHILE i < 22
  122.                      begin
  123.                      z := 4;
  124.                      end;
  125.                 end
  126.            else begin
  127.                 b := 1;
  128.                 end;
  129.  
  130.       With a level change of 4 or 5 spaces, code on the same lexical level
  131.       stands out, making it easier to spot unmatched begin/ends and other
  132.       syntactical problems. The objection I've heard to 5 char indentation
  133.       is that you run out of room on the right side of the line.  My answer
  134.       is that in most cases, if you have to indent 4 or 5 levels, the
  135.       procedure should probably have been broken down into multiple procedures
  136.       anyway.
  137.  
  138. 5. I can live with most combinations of upper and lower case letters, as long
  139.       as it is reasonably consistant.  I have seen good use of capitalization
  140.       of language elements, lower case variables and also the opposite.  I
  141.       came from the punch-card all capitals world, went to a religiously
  142.       all lower-case shop and wound up muddled.  Over-use of upper case is
  143.       hard on the eyes without contributing much information.
  144.  
  145. 6. One of the most useful and hardest conventions to do well is to name
  146.       variables, functions and procedures in such a way as to have the
  147.       name imply its origin and/or use.  If all of your global boolean
  148.       flag variables are named xxxxFlag then it is much easier to
  149.       read " If PrintFlag then ...".  I tend to make symmetric functions
  150.       and procedures, even when I don't need the reverse operation at present,
  151.       just so it will be there later.  So, if I convert integer to string
  152.       with IntegerString, I will code, or at least mentally reserve procedures
  153.       for RealString, StringInteger for later.  This also allows me to see
  154.       if the syntax is obvious, or at least straight-forward.
  155.  
  156. 7. The single hardest coding function is CHANGE.  When libraries have
  157.       been built up and 20 or 30 programs are using them, how can you
  158.       rename a low level procedure?  This is a problem with no easy
  159.       solution.  Some of it can be avoided by naming well early.  Some
  160.       can be avoided by hiding functions inside units and objects.  Some
  161.       can be fixed by good coding tools search and replace text processors
  162.       and the like.   The problem is magnified greatly with multiple sites.
  163.  
  164. \new
  165. Program Construction - Detail
  166.  
  167.      The following is a list of recommended procedures.  I will try
  168. to use them in my code.  They may not be good for all people, but
  169. they work for me.
  170.  
  171. \join off
  172. Variables.
  173.  
  174.   1. Use as few global variables as possible.
  175.  
  176.   2. Reserve one and two character names for temporary type variables
  177.       A procedure should declare them locally.  Global temporaries cause
  178.       no end of trouble because the contents are uncertain.
  179.        var s,s1,s2 ... : string;
  180.            i,j,k       : integer;     { an old FORTRAN hold-over}
  181.            b           : byte;
  182.  
  183.   3. Except for very specific uses, don't bother with specific length
  184.       strings.  Var ext : string;  for holding file extensions is a
  185.       waste of 250+ bytes of data space, but the alternatives of
  186.       creating a   type ext_string = string[3]; causes pains in
  187.       parameter passing and declarations(what did I name that file
  188.       extension type? "extstring"? "type_ext"? ...)  Simply declaring
  189.       variables string[3] is a real disaster when you want to change it
  190.       to string[4].
  191.  
  192.       It is worth noting that use of objects tends to move a lot of data
  193.       space onto the heap which is much more plentiful.
  194.  
  195.   4. Choose variable names such that the code which uses them can be
  196.       read out loud.  "DO PlaceStringOnHeap(s) until ...;" Reads better
  197.       than "DO HeapString(s) until ..."
  198.  
  199.   5. Conversely, use of 3 or 4 descriptive names in a single statement
  200.       can be very hard to follow, even though technically correct.
  201.         "If (IndexMaximum > NumberofDataItems) then IncreaseSizeofDataArea;"
  202.       reads like a ton of bricks.   "NdxMax", "DataCnt",  and other frequently
  203.       used shortcuts are no less readable, and save typing and spelling
  204.       errors.  The trick is to always use the same shortcut for the same
  205.       word.
  206.  
  207.   6. The world needs to agree on the meaning of a few terms, then use
  208.       them appropriately.  One man's "indent" is another woman's "offset"
  209.       or "margin" or "leftmargin" or "pad" ...  This winds up being critical
  210.       for providing run-time options for utility programs.  One way to
  211.       solve this is to have the library provide "free" decoding for
  212.       a host of standard options.  It then becomes much easier to use
  213.       the provided options rather than code your own support.
  214.  
  215.   7. Write your code such that 50+% of it is re-useable.  EVERY program
  216.       should contribute at least one routine to your library.  Primarily
  217.       this breaks down to taking one step back when coding and separating
  218.       the exact problem you are attempting to solve from the more general
  219.       methods you are using to solve it.  For example, if you need to
  220.       decode a string which looks like "xxxxx(yyy)" into the x and y pieces,
  221.       write the routine to pass the delimiter pair as arguments (or
  222.       global variables, or compile time constants), and name the routine
  223.       such that you know that the function is general.  Spend an extra 10%
  224.       of time adding error checking code and then the next program will
  225.       have a "free" component.
  226.  
  227.       The cost of this (there is ALWAYS a cost) is most probably run-time
  228.       efficiency.  Generalized code will not be quite as tight as code
  229.       which solves exactly the one specific problem.  It has been 15-20
  230.       years since the cost of hardware was more important than programming/
  231.       debugging costs.  Hardware seems to improve by a factor of 2 every
  232.       year, programmers pick up maybe 10% per year from better tools and
  233.       experience.  My vote is - when given a choice between ease of coding
  234.       and speed of running, take the coding and go back and optimize later.
  235.       Chances are, you won't need to.